get-value

What is get-value?

The get-value npm package is used for safely retrieving nested values from an object or array. It is useful when dealing with deeply nested structures where checking for the existence of each level can be cumbersome. It allows for specifying paths to the desired value using a string or an array of keys/indices.

What are get-value's main functionalities?

Get nested values

Retrieve a nested value from an object using a string path.

const get = require('get-value');
const obj = { a: { b: { c: 'd' } } };
console.log(get(obj, 'a.b.c')); // 'd'

Use array paths

Retrieve a nested value using an array of keys as the path.

const get = require('get-value');
const obj = { a: { b: { c: 'd' } } };
console.log(get(obj, ['a', 'b', 'c'])); // 'd'

Specify default values

Provide a default value to return if the full path does not exist.

const get = require('get-value');
const obj = { a: { b: { c: 'd' } } };
console.log(get(obj, 'a.b.e', { default: 'default value' })); // 'default value'

Split string paths

Retrieve values from keys that include a dot or other special characters by specifying a custom separator.

const get = require('get-value');
const obj = { 'a.b': { c: 'd' } };
console.log(get(obj, 'a\.b.c', { separator: '\.' })); // 'd'

Other packages similar to get-value

lodash.get

lodash.get is a method from the Lodash library that provides similar functionality to get-value. It allows for retrieving nested values with a default option. Lodash is a larger utility library, so lodash.get is part of a broader suite of tools.

dot-prop

dot-prop is another package that allows for getting and setting nested properties. Unlike get-value, dot-prop also supports setting values. It uses a dot notation string as the path.

deep-get-set

deep-get-set is a package that not only gets but also sets deep values. It is less popular than get-value and does not have as many configuration options.

README

get-value

Use property paths (a.b.c) to get a nested value from an object.

Benchmarks

This is 10x faster and more performant than dot-prop, and it passes all of the dot-prop tests.

Of the libs benchmarked, dot-prop was the least performant:

#1: deep
  get-value x 3,308,335 ops/sec ±1.32% (94 runs sampled)
  dot-prop x 197,631 ops/sec ±1.27% (94 runs sampled)
  getobject x 218,635 ops/sec ±1.51% (91 runs sampled)

#2: shallow
  get-value x 5,762,976 ops/sec ±1.21% (95 runs sampled)
  dot-prop x 695,892 ops/sec ±1.42% (95 runs sampled)
  getobject x 724,493 ops/sec ±1.46% (93 runs sampled)

Also, get-value supports escaping dots in paths, which is common when object keys are file paths with extensions, dot-prop does not.

Install

Install with npm

$ npm i get-value --save

Install with bower

$ bower install get-value --save

Usage

var get = require('get-value');

var obj = {a: {b : {c: {d: 'foo'}}}, e: [{f: 'g'}]};
get(obj, 'a.b.c');
//=> {d: 'foo'}

get(obj, 'a.b.c.d');
//=> 'foo'

get(obj, 'e[0].f');
//=> 'g'

key as an array

Optionally pass the key as an array (this is useful when you need to dynamically build up the property name)

var obj = {a: {b: 'c'}};
get(obj, ['a', 'b']);
//=> 'c'

Related projects

• has-any: Returns true if an object has any of the specified keys. | homepage
• has-any-deep: Return true if key exists deeply on the given object. | homepage
• has-value: Returns true if a value exists, false if empty. Works with deeply nested values using… more | homepage
• set-value: Create nested values and any intermediaries using dot notation ('a.b.c') paths. | homepage
• unset-value: Delete nested properties from an object using dot notation. | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Running tests

Install dev dependencies:

$ npm i -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2014-2015 Jon Schlinkert Released under the MIT license.

---

This file was generated by verb-cli on October 28, 2015.